Variables
Previous  Top  Next



Variables hold data on which a program operates. In the Clip text, the variable's name represents the value of data stored somewhere in the computer memory when the Clip is executed. The data can be anything from nothing to multiple megabytes of text, and can represent a string (a sequence of characters), an integer (negative and positive whole numbers), or a boolean (True/False) data type.

A variable name can be made up of any character except those that delimit words (space, tab, punctuation, carriage return, etc.). The name must also be bound by a percentage character "%". The left side "%" must be preceded with a circumflex accent "^" when you are referring to the value it contains. Example of a variable: ^%MyVariable%. In NoteTab, a variable is defined as soon as its name is encountered in a Clip during execution. A variable can be placed anywhere in a Clip text and can even be used to define a command or function name. If you haven't initially assigned a value to it, the variable is always empty at first.

Variables keep their value as long as the Clipbook is kept open. NoteTab recognizes two types of variables: local variables that exist only within the context of the library that created them (they are cleared if you change libraries or close the Clipbook), and permanent variables that keep their value even when you change libraries (but not if you close the Clipbook). Add the prefix "p_" to define a permanent variable (e.g. ^%p_KeepValue%). If you want to preserve a variable's value even after closing NoteTab, you can store it in an INI file by using the "^!SaveValue" command and then restore it later by using the "^$GetValue()$" function.

Use the "^!Set" command to assign data to a variable. For example:
^!Set %VariableName%=Data
If %VariableName% was never used before, it will be created by the command and then receive the value assigned to it after the equal sign. If %VariableName% already exists, the above command will replace the value it contains with the new data. Note that you must not precede the variable name with a circumflex accent "^" when you assign or change its value.

You can also assign values to multiple variables using a single "^!Set" command. An assignment must be separated from the next one with a semicolon and a blank character "; ". For example:
^!Set %V1%=Value1; %V2%=Value2; %V3%=Value3
Note that the last assignment does not end with a semicolon.

Note that you must use the curly braces format ^?{ } rather than the square brackets ^?[ ] if you want to assign the result from a Clip wizard memo field. Example:
^!Set %NewVariable%=^?{(T=M)Message}


To use the data contained in a variable, just precede the variable name (bound by "%" characters) with a circumflex accent: ^%VariableName%
anywhere in the Clip where you want to use it. Note that you cannot define a label with a variable. So, for example, the following will not work (the line is just ignored):
:^%VariableName%

Note that you can set the value of a variable with the data contained in another variable by using the following instruction:
^!Set %NewVariable%=^%OtherVariable%

The Clipbook also provides predefined variables. Unlike other variables, they already contain a value when you first use them. You may, however, reassign other values to them if you wish. These are the predefined variables and the data they contain:

^%AR_KEY% = Auto-replace activation key (added in v4.6)  
^%AR_WORD% = Auto-replace text (added in v4.9)  
^%CARET% = caret (^) (added in v4.6)  
^%COLON% = colon (:)  
^%EMPTY% = empty string  
^%NL% = new line (CR/LF pair)  
^%PAGE% = Page break  
^%RESULT%= Used to assign result to custom functions (added in v4.8)  
^%SC% = semicolon (;)  
^%SPACE% = Blank space character  
^%TAB% = Tab character  
^%VBAR% = vertical bar (|) (added in v4.6)  


Commands:

^!Append
%Variable%=Value
Appends value to the content of %Variable%. This command also has the advantage of allowing assignments of function names and ^?{} prompts without causing these to be evaluated. This command is particularly useful for creating sophisticated Clip Wizards.

^!ClearValue [Section:]Key
Deletes the specified key in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is searched under the [ClipValues] section. Section names are only supported since version 4.51.

^!ClearValues [Section]
Deletes all the keys under the specified section in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the [ClipValues] section will be cleared. Section names are only supported since version 4.51.

^!ClearVariable %VariableName%
Empties the specified variable.

^!ClearVariables
Clears all variables (including those defined as permanent).

^!Dec VariableName [nn]
Subtracts 1 from specified variable (decrement). If you use the second optional parameter "nn", you can specify a different decrement value. For example, if %var% contains the value 30 and you apply the command "^!Dec %var% 7" to it, the new value will be 23.

^!Inc VariableName [nn]
Adds 1 to specified variable (increment). If you use the second optional parameter "nn", you can specify a different increment value. For example, if %var% contains the value 23 and you apply the command "^!Inc %var% 7" to it, the new value will be 30.

^!ProgIniLoad [IniName] (added in v4.6)
Loads options from the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it must exist or else the command sets the error condition). Note that the [AutoLoad] section is ignored by this command.

^!ProgIniSave [IniName] (added in v4.6)
Saves the current program settings into the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it is automatically created if it does not exist).

^!SaveValue [Section:]Key=Value
Saves the key and its value in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is written under the [ClipValues] section. Section names are only supported since version 4.51. The maximum amount of text that can be saved this way is 1024 characters. Example:
^!SaveValue MySection:UserName=Raymond


^!Set %VariableName%=Value
or
^!Set %VariableName%=^%OtherVariable%
or
^!Set %V1%=Value1; %V2%=Value2; %V3%=Value3
Assigns Value to VariableName. The variable name may not contain blanks or other word-delimiting characters. The value can be a string, an integer, or a boolean data type. It can also refer to the value of another variable.

^!SetArray %VariableName%=ArrayData (added in v4.6)
Similar to the ^!Set
command but creates an array from the data assigned to it. By default, the data delimiter is a plain semi-colon (;), or a semi-colon and double-quotes separating each item. You can change the default delimiter with the command ^!SetListDelimiter (see below). During the assignment, the individual items from the ArrayData are each stored in a new variable with the same name as the base variable plus an index number reflecting their corresponding position. The variable at index 0 has a special purpose as it stores the actual number of items contained in the array. You can change the values of the individual indexed items by using the ^!Set, ^!Inc, ^!Dec commands, and the changes are reflected in the base variable. If you assign an empty value to an array variable, or use the ^!Set command to assign a new value to it, the array is automatically removed from memory.

Examples:
^!SetArray %Array%="Value 1";"Value 2";"Value 3"
The above instruction will create four new variables:
^%Array0% = 3
^%Array1% = Value 1
^%Array2% = Value 2
^%Array3% = Value 3
If we assign a new value to the second item, as follows:
^!Set %Array2%=New Value
then accessing the base variable ^%Array% will return:
"Value 1";"New Value";"Value 3"
The following assignment will destroy the array, and only the base variable will be preserved with the newly assigned value:
^!Set %Array%=Another Value

^!SetCode %VariableName%=Value (added in v4.84)
Similar to the ^!Set command, but assigns the value without interpreting ^?{} prompts and Clip tokens like ^P, ^T, ^&, ^#, etc. However, variables and functions used in the assigned value are evaluated normally. You cannot set multiple variables with this command.

^!SetIniFile Name (added in v4.51)
Defines where Clip variables are saved when using the SaveValue, ClearValue, and ClearValues commands and the GetValue function. By default, variables are saved in NoteTab's INI file (or registry if so configured). Use this command to define a different INI file. If you do not specify a path in the name, the specified INI file will be created in the Libraries directory. If you plan to distribute your library file, consider giving your INI file the same name as your library file (without the extension); you can use the ^$GetLibraryName$ for this purpose. The scope of this command is limited to the library in which it is invoked. It is reset when you change libraries or close the Clipbook. Invoke the command with no name to reset NoteTab's INI file as the default.

^!SetListDelimiter Value (added in v4.6)
Defines a delimiter to be used by the ^!SetArray
command or Clip Wizard fields using the new Checkbox list (see below). Tokens are accepted, but the delimiter must not be more than 10 characters. The scope of this command is limited to the current Clip. Assigning an empty value results in using the default semi-colon (;) delimiter. Example: ^!SetListDelimiter ^p^p


Functions:

^$GetIniFile$
Returns the name of the INI file defined by the SetIniFile command. Returns a blank string if NoteTab's INI file is used.

^$GetValue("[Section:]Key")$
Reads the specified key in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is searched under the [ClipValues] section. Section names are only supported since version 4.51. Returns the value assigned to the key. Returns an empty string if the key does not exist. Example based on ^!SaveValue example: ^$GetValue(MySection:UserName)$ -> Raymond